LocalServer Sample Readme

Introduction

The LocalServer sample demonstrates 2 methods for a process running under Classic to communicate with a process running under Mac OS X. There are 2 methods for this "InterArchitecture" communications. One method is to use AppleEvents.  The second method is to use networking with a server on the Mac OS X side and a client on the Classic side.  This sample demonstrates both techniques.

Sample Description

The LocalServer Project Builder project builds the "LocalServer" application. LocalServer implements a TCP server which will only accept connections from a client on the same system. The server checks the source IP address of the connection request and requires a match with its own IP address before accepting the connection.

The design of the server is to receive data, then respond to the sender with the same message. In this example, the incoming data is an OTTimeStamp value which represents the timestamp when the packet was sent.

Considerations/Caveats

The LocalServer sample requires an active TCP connection, via built-in ethernet, thru other ethernet port (e.g. Airport), or thru an active PPP connection. If there is no active TCP connection, the OTOpenEndpoint calls under Classic will still work and the OTBind call will bind the endpoints to IP Address 0.0.0.0. The Shared IP module which routes packets between the Classic and OS X environment will not transfer packets which do not have a valid address. As a side note, the Shared IP module will not transfer with the link local loopback address 127.0.0.1, between Classic and OS X.

The LocalServer Sample will not work with the following releases of Mac OS X: Mac OS X 10.1 thru 10.1.4. There is a known issue with the Sharing IP module such that TCP communications on the same system between processes running within Classic cannot communicate with TCP processes running in Mac OS X.  The LocalServer Server sample checks for the version of Mac OS X present and will quit if an unsupported release of Mac OS X is present.

Note that the server implements an OT handoff endpoint. This is required since on Mac OS X, the BSD subsystem, which is under the Open Transport shim, doesn't handle the transition of a server socket back to the LISTENING state after an orderly disconnect with the client in the STREAMS networking sense. 

Note also that once the orderly disconnection has occurred, the handoff endpoint is unbound via the OTUnbind call. It was found that if the endpoint remains bound, then when a new connection is handed off to the handoff endpoint, that a new port resource is allocated and the previous port continues to exist until the 2 minute inactivity timer releases the port. By unbinding the endpoint, the lower layer BSD socket is also released.

The Client sample is supplied in 2 forms - a non_carbon version to use to test under classic and a carbon version to test under OS X. Both samples begin by issuing an Apple Event to check for the presence of the LocalServer and to obtain the IP address and port number to use to communicate with the server. When the server responds with this information, a TCP endpoint is created and a connection established with the server. Note that since the client is going to send small (8-byte) packets, the NO_DELAY IP option is enabled.

The client gets the current OTTimeStamp and sends the value to the server. The server receives the data and send it back to the sender. The client program receives the data back and displays the roundtrip time in milliseconds. One cannot measure the one way trip time since the OTGetTimeStamp call will not return the same time stamp under the X environment and the Classic environment. For this reason, the roundtrip time provides a better indicator of packet latency. You can compare the performance with the Carbon version of the client.

The LocalServer sample and client use the TCP protocol to communicate with each other. The sample can easily be modified to use the UDP protocol instead. On the server side, once the UDP endpoint is bound it will wait listening for incoming data. In processing the T_DATA event, the sample would have to be modified to use the OTRcvUData call instead of OTRcv.  

Building Sample

CodeWarrior 7.0 was used to build the CodeWarrior samples. Project Builder 1.1.1 was used to build the LocalServer sample.

The CodeWarrior project for the client provides 2 different targets, one a Carbon Target includes the Carbon.r file which defines the 'carb' resource so that the application runs under OS X. This target also includes the "Prefix.h" file so that the proper defines are in place for the OTNotifierUPP to be processed correctly. The non-carbon target creates a client application which will only run under the Classic environment or under Mac OS 8/9.

Both of these applications were built on sample frameworks which utilizes the WaitNextEvent function at the core of the main event loop. The server implements  asynchronous reads and writes of data so is not affected by this model. The client sample issues synchronous writes and reads.

